<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- -*- Bolio -*- -->
<!-- *** This is a very rough draft *** -->
<!-- Use of the words 'object' and 'instance' -->
<!-- Standardize singular/plural in defflavor options? -->

<div class='chapter' id='21'>21. </div>
<p class='cindent'><!-- flavor -->
<p class='cindent'><!-- message -->
<p class='cindent'><!-- method -->
<p class='cindent'><!-- object -->
<p class='cindent'><!-- instance -->

<div class='section' id='21.1'>21.1 </div>
The flavor system is basically a set of conventions and mechanisms for
organizing programs.  It provides a good way to organize complex
programs built out of many parts, and helps to define the interfaces
between the parts cleanly.  Flavors are based on the
object-oriented-programming ideas of Simula and Smalltalk, with some
additional new ideas about modularity.

Some of the basic concepts of the flavor system are:

<table>
<tr valign='top'>
<td><font class='lisp'> Objects</font></td><td>The world is viewed as containing a number of <!-- open: 1, close: 0 --><font class="italic">objects</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED -->.  Each
object has several <!-- open: 2, close: 1 --><font class="italic">operations</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED --> which may be performed upon it.
An object contains some <!-- open: 3, close: 2 --><font class="italic">state</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED --> which it remembers; operations
frequently have side-effects upon the state as well as upon other,
related, objects in the world.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Message-Passing</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The description of how an operation is to be performed on an object is embedded
inside that object.  This is in distinction to the traditional
functional organization, in which there is a program for each operation
which contains a conditional to select the behavior based on the type
of the object.
This is only a difference in convention; the two organizations
are really the same except for the way they are indexed.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Types</font></td><td>Structure is imposed upon this world through the idea of <!-- open: 4, close: 3 --><font class="italic">types</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED -->.
Several objects can be said to have the same type if they behave the
same with respect to their operations.  This idea is actually quite
fuzzy, as the behavior of an object is affected by its state and by
its relations with other objects, as well as by its type.  In implementation
terms, two objects have the same type if their behavior is implemented
by the same description, or program.  Another way that the idea of type
is fuzzy is that two objects can have the same type with respect to some aspects
of their behavior, while differing in other aspects.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Type Combination</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>New types, that is, new repertoires of object behavior, can be constructed
by combining existing types.  The flavor system's main contribution
is the provision of mechanisms by which this combination may be done
flexibly and painlessly.  The required amount of unmodular knowledge of the internal
details of the types being combined is minimized.
</td></tr><!-- item_ --></table><!-- end table -->


Here are some of the jargon words used by the flavor system.

<table>
<tr valign='top'>
<td><font class='lisp'> Flavor</font></td><td>A <!-- open: 5, close: 4 --><font class="italic">flavor</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED --> is a description of the nature and behavior of objects.
The word flavor is used rather than <!-- open: 6, close: 5 --><font class="italic">type</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 7, close: 6 --><font class="italic">class</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 8, close: 7 --><font class="italic">category</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED -->,
or <!-- open: 9, close: 8 --><font class="italic">set</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED --> to avoid the pre-existing connotations of those words,
and to distinguish flavors from other implementations of similar ideas
also present in the Lisp machine system.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Mixin Flavor</font></td><td>A flavor need not be a complete description.  A <!-- open: 10, close: 9 --><font class="italic">mixin</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED --> flavor describes
only a single aspect of objects' behavior.  It is a module which can be
combined with other flavors to produce a complete description.
The resulting combination is itself a flavor.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Base Flavor</font></td><td>Types can themselves be organized by types.  There may be many types of
objects, all of which have certain operations in common and are directed
at the same basic goal; they can be said all to belong to the same
<!-- open: 11, close: 10 --><font class="italic">base type</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED -->.  A <!-- open: 12, close: 11 --><font class="italic">base flavor</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED --> is a description of what those
many types have in common, and what are the conventions they share.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Method</font></td><td>A <!-- open: 13, close: 12 --><font class="italic">method</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED --> is a function which implements a certain operation on
objects of a certain flavor.  Like all Lisp functions, it takes arguments,
returns results, and may have side-effects.  An important part of the
flavor system is the mechanism for combining methods for the same operation
that come from different flavors.  Thus a single method is not responsible for the
whole of an operation; it only takes care of its flavor's portion of the
operation.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Message</font></td><td>A <!-- open: 14, close: 13 --><font class="italic">message</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED --> name is a symbol which is the name of an operation.
Performing an operation on an object is done by "sending a message" to
that object.  This is implemented as calling the object as a function,
with the first argument the message (or operation) name, and the
succeeding arguments the arguments to the message.  The flavor system
uses the message symbol to find and invoke the appropriate method or
methods, passing them the arguments.  Message symbols are typically interned in
the keyword package, thus they are prefixed with colons.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Instance</font></td><td><!-- open: 15, close: 14 --><font class="italic">Instances</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED --> are the implementation of the notion of object.  A flavor
may be <!-- open: 16, close: 15 --><font class="italic">instantiated</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED -->; this produces an object whose nature and behavior
are described by that flavor.  A flavor may be instantiated any number
of times, producing any number of distinct objects with similar behavior.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Instance-Variable</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The state of an object is maintained as the values of a set of
<!-- open: 17, close: 16 --><font class="italic">instance variables</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED -->, names for the parts of an object's state.
Inside a method, the instance variables appear as Lisp variables which
may be used and <!-- open: 18, close: 17 --><font class="lisp">setq</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED -->'ed.  Everything private to a particular
instance is in the instance variables and everything shared between
instances of the same flavor is part of the flavor.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Initialization</font></td><td><!-- open: 19, close: 18 --><font class="italic">Initialization</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->, usually abbreviated <!-- open: 20, close: 19 --><font class="italic">init</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED -->, is an operation which
is performed on an object when it is created.  This involves complex issues
and will be explained later.
</td></tr><!-- item_ --></table><!-- end table -->


It is important to understand the notion of <!-- open: 21, close: 20 --><font class="italic">flavor combination</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED -->.  A
flavor is typically constructed out of several other flavors, called its
<!-- open: 22, close: 21 --><font class="italic">components</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED -->.  A flavor has some methods and instance variables of its
own, and inherits others from its components.  The components are
combined in a particular order, specified when you define the flavor.
Depth-first ordering is used; that is, if the components of <!-- open: 23, close: 22 --><font class="italic">flavor-1</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED -->
specified by its definition are <!-- open: 24, close: 23 --><font class="italic">flavor-2</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 25, close: 24 --><font class="italic">flavor-3</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED -->, and the
components of <!-- open: 26, close: 25 --><font class="italic">flavor-2</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED --> are <!-- open: 27, close: 26 --><font class="italic">flavor-2a</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 28, close: 27 --><font class="italic">flavor-2b</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED -->, then
<!-- open: 29, close: 28 --><font class="italic">flavor-2a</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 30, close: 29 --><font class="italic">flavor-2b</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED --> come before <!-- open: 31, close: 30 --><font class="italic">flavor-3</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED --> in
<!-- open: 32, close: 31 --><font class="italic">flavor-1</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED -->'s fully-expanded list of components.  Flavors earlier in
the list of components are thought of as higher-level, more outside,
more in control, or less basic than those later in the list of components.
For uniformity, a flavor is always the first in its own list of components.

Thus the first step in combining flavors is constructing the expanded list
of components, so that all flavors which contribute in any way to the
flavor being defined are enumerated, and their order is known.  The
remaining steps are <!-- open: 33, close: 32 --><font class="italic">instance-variable combination</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 34, close: 33 --><font class="italic">method combination</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED -->.
(Certain minor flavor features, such as the default-init-plist, are also combined.
But this doesn't involve any non-obvious issues.)

Instance-variable combination is simple; instance variables with the
same name are the same.  Thus different components of a flavor may
communicate through shared instance variables.  Typically one component
flavor is "in charge" of an instance variable, while others just look at
it.  The initial value for an instance variable comes from the first
component flavor that specifies one.  To keep instance variables
distinct, use the same mechanism as to keep any other type of symbols
distinct: packages.

Method combination is the heart of the flavor system.  When a flavor is
defined, a single function, called a <!-- open: 35, close: 34 --><font class="italic">combined method</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED -->, is constructed
for each message supported by the flavor.  This function is constructed out
of all the methods for that message from all the components of the flavor.
There are many different ways that methods can be combined; these can be
selected by the user when a flavor is defined.  The user can also create
new forms of combination.

The default way to combine methods is the <!-- open: 36, close: 35 --><font class="italic">daemon</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --> paradigm.  Methods
are classified into two kinds, <!-- open: 37, close: 36 --><font class="italic">primary</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 38, close: 37 --><font class="italic">daemon</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED -->.  The idea is
that one flavor is "in charge" of the main business of handling a
message, while other flavors just want to keep informed, or just want to
do the part of the operation associated with their own area of
responsibility.  The method-combination process selects one primary
method for a message; it comes from the first component flavor that has
one.  Any primary methods belonging to later component flavors are
ignored.  Daemon methods come in two kinds, <!-- open: 39, close: 38 --><font class="italic">before</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 40, close: 39 --><font class="italic">after</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED -->.
The <!-- open: 41, close: 40 --><font class="italic">combined method</font><!-- open: 41, close: 41 --> <!-- MATCHED MATCHED MATCHED --> consists of all the before daemons, then the
primary method, then all the after daemons.  The returned values from
the combined method are the values returned by the primary method; any
values from the daemons are ignored.  Before-daemons are called in the
order that flavors are combined, while after-daemons are called in the
reverse order.  Note that if you have no daemons, this reduces to the
form of inheritance traditional in message-passing systems.

Other ways of combining methods will be detailed later (see <font color='red'>LINK:(</font>method-combination)).

<!-- .bullshit -->
<!-- Object-oriented modular programming.  Evolved out of the class -->
<!-- idea of smalltalk and simula. -->
<!-- The world is viewed as containing several objects.  Each object -->
<!-- can be manipulated using a set of specified operations.  The details -->
<!-- of how a particular operation works on an object are contained in the particular object -->
<!-- (rather than in a program for the particular operation) -->
<!-- and may vary from one object to another.  This supports a ... where -->
<!-- there are several objects, all of the same general type (that is -->
<!-- the same operations upon them are meaningful (r-p)), but which -->
<!-- differ in flavor (that is the detailed behavior of the operations -->
<!-- differs.)  [example] -->
<!-- In object-oriented programming the program is organized around -->
<!-- descriptions of the bahavior of objects rather than around descriptions -->
<!-- of objects. -->
<!-- The flavor system provides for modularity by making it easy to create -->
<!-- a new flavor by combining several existing flavors (which usually -->
<!-- are of the same general type.) -->
<!-- The idea of "general type" is fuzzy and not formalized ... almost -->
<!-- the same general type. -->
<!-- Flavors come in 3 kinds ... this is not formalized by the system ... -->
<!-- basic flavors (which define a general type), component flavors -->
<!-- (which are not complete descriptions on their own, but exist to be -->
<!-- combined into complete flavors), and complete flavors, which can -->
<!-- be instantiated into objects.  [r-p] -->
<!-- How about calling them base flavors, mix-ins, and complete flavors? -->
<!-- Stock?? -->
<!-- Stock?? -->
<!-- An object consists of local state (values of instance variables) -->
<!-- and a collection of methods (functions which describe how to -->
<!-- perform operations / respond to messages).  Methods take arguments, -->
<!-- return results, examine and modify the instance variables' values, -->
<!-- and have side-effects in the general environment.  Operations -->
<!-- are named by keyword symbols. -->
<!-- are named by keyword symbols. -->
<!-- Daemon methods useful for combining component (mix-in) flavors. -->
<!-- The idea is as follows.  In the simplest case, you combine flavors -->
<!-- which are completely unconnected.  This is very easy, each has its -->
<!-- own instance variables, and messages are simply sent to whichever -->
<!-- flavor cares.  Then you can have shared instance variables.  Any instance -->
<!-- variables with the same name in the same package will be shared -->
<!-- (just as with any other kind of names in Lisp).  Different flavors -->
<!-- mixed together can communicate through shared instance variables; -->
<!-- typically one flavor is "in charge" of an instance variable and others -->
<!-- just look at it.  A more difficult case of combining flavors occurs -->
<!-- when more than one flavor is interested in the same message.  Commonly -->
<!-- this can be organized in such a way that the dependency between flavors -->
<!-- is minimized; one flavor is "in charge" of that message, while others -->
<!-- simply want to be informed that it has happened.  The flavor system allows -->
<!-- before- and after-daemon methods, which get called before or after the -->
<!-- primary method.  Only the primary method can return a value, and there -->
<!-- can be only one primary method. -->
<!-- [Try to concoct an example.  Is there anything useful in Howrad's paper?] -->
<!-- [[One example is the refresh method of the window system, which tells a window -->
<!-- to refresh its image on the screen.  The primary method does most of the work, -->
<!-- while mix-in flavors have daemons to take care of their own part of the image, -->
<!-- such as the outline, the label, the blinkers, etc., and to note that the -->
<!-- screen has been refreshed.  [[[This may not actually be accurate.]]] -->
<!-- ]] -->
<!-- .end_bullshit -->

[Much work still required here.]

[This paragraph is important and should be expanded.  It is what
the idea of "conventions" is all about.]
The idea of the external contract for an operation and the internal(?)
details of the different flavors of that operation.  Or, the idea
of the external contract for objects conforming to a certain general
type, and the specific details of particular flavors of objects.

<div class='section' id='21.2'>21.2 </div>
<div class='defmac' id='defflavor'><font class='exdent'><font class='funcname' id='defflavor'>defflavor</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->A flavor is defined by a form
<pre class='lisp'>
(defflavor <!-- open: 42, close: 41 --><font class="italic">name</font><!-- open: 42, close: 42 --> <!-- MATCHED MATCHED MATCHED --> (<!-- open: 43, close: 42 --><font class="italic">var1</font><!-- open: 43, close: 43 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 44, close: 43 --><font class="italic">var2</font><!-- open: 44, close: 44 --> <!-- MATCHED MATCHED MATCHED -->...) (<!-- open: 45, close: 44 --><font class="italic">flav1</font><!-- open: 45, close: 45 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 46, close: 45 --><font class="italic">flav2</font><!-- open: 46, close: 46 --> <!-- MATCHED MATCHED MATCHED -->...)
	<!-- open: 47, close: 46 --><font class="italic">opt1</font><!-- open: 47, close: 47 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 48, close: 47 --><font class="italic">opt2</font><!-- open: 48, close: 48 --> <!-- MATCHED MATCHED MATCHED -->...)
</pre>
<!-- open: 49, close: 48 --><font class="italic">name</font><!-- open: 49, close: 49 --> <!-- MATCHED MATCHED MATCHED --> is a symbol which serves to name this flavor.  It will be returned
by <!-- open: 50, close: 49 --><font class="lisp">typep</font><!-- open: 50, close: 50 --> <!-- MATCHED MATCHED MATCHED --> of an instance of this flavor, and will get an <!-- open: 51, close: 50 --><font class="lisp">si:flavor</font><!-- open: 51, close: 51 --> <!-- MATCHED MATCHED MATCHED -->
property of the internal data-structure containing the details of the flavor.
<!-- open: 52, close: 51 --><font class="lisp">(typep <!-- open: 53, close: 51 --><font class="italic">obj</font><!-- open: 53, close: 52 --> <!-- open: 54, close: 52 --><font class="italic">flavor-name</font><!-- open: 54, close: 53 -->)</font><!-- open: 54, close: 54 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 55, close: 54 --><font class="lisp">t</font><!-- open: 55, close: 55 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 56, close: 55 --><font class="italic">obj</font><!-- open: 56, close: 56 --> <!-- MATCHED MATCHED MATCHED --> is an instance
of a flavor, one of whose components is <!-- open: 57, close: 56 --><font class="italic">flavor-name</font><!-- open: 57, close: 57 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- open: 58, close: 57 --><font class="italic">var1</font><!-- open: 58, close: 58 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 59, close: 58 --><font class="italic">var2</font><!-- open: 59, close: 59 --> <!-- MATCHED MATCHED MATCHED -->, etc. are the names of the instance-variables
containing the local state for this flavor.  A list of the name of an
instance-variable and a default initialization form is also acceptable;
the initialization form is only evaluated if no other initial value for
the variable is obtained.  If no initialization is specified, the variable
remains unbound.

<!-- open: 60, close: 59 --><font class="italic">flav1</font><!-- open: 60, close: 60 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 61, close: 60 --><font class="italic">flav2</font><!-- open: 61, close: 61 --> <!-- MATCHED MATCHED MATCHED -->, etc. are the names of the component flavors out of
which this flavor is built.  The features of those flavors are inherited
as described above.

<!-- open: 62, close: 61 --><font class="italic">opt1</font><!-- open: 62, close: 62 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 63, close: 62 --><font class="italic">opt2</font><!-- open: 63, close: 63 --> <!-- MATCHED MATCHED MATCHED -->, etc. are options; each option may be either a
keyword symbol or a list of a keyword symbol and arguments.  The options
to <!-- open: 64, close: 63 --><font class="lisp">defflavor</font><!-- open: 64, close: 64 --> <!-- MATCHED MATCHED MATCHED --> are described on <font color='red'>LINK:(</font>defflavor-options).
</div>

<div class='defvar' id='*all-flavor-names*'><font class='exdent'><font class='funcname' id='*all-flavor-names*'>*all-flavor-names*</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->This is a list of the names of all the flavors that have ever been <!-- open: 65, close: 64 --><font class="lisp">defflavor</font><!-- open: 65, close: 65 --> <!-- MATCHED MATCHED MATCHED -->'ed.
</div>

<div class='defmac' id='defmethod'><font class='exdent'><font class='funcname' id='defmethod'>defmethod</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->A method, that is, a function to handle a particular message sent to
an instance of a particular flavor, is defined by a form such as
<pre class='lisp'>
(defmethod (<!-- open: 66, close: 65 --><font class="italic">flavor-name</font><!-- open: 66, close: 66 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 67, close: 66 --><font class="italic">message</font><!-- open: 67, close: 67 --> <!-- MATCHED MATCHED MATCHED -->) <!-- open: 68, close: 67 --><font class="italic">lambda-list</font><!-- open: 68, close: 68 --> <!-- MATCHED MATCHED MATCHED -->
  <!-- open: 69, close: 68 --><font class="italic">form1</font><!-- open: 69, close: 69 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 70, close: 69 --><font class="italic">form2</font><!-- open: 70, close: 70 --> <!-- MATCHED MATCHED MATCHED -->...)
</pre>

<!-- open: 71, close: 70 --><font class="italic">message</font><!-- open: 71, close: 71 --> <!-- MATCHED MATCHED MATCHED --> is either just a keyword symbol which names the message
to be handled, or two keyword symbols, the first of which is the method type
and the second of which is the message name.  The meaning of the
method type depends on what kind of method-combination is declared
for this message.  For instance, for daemons <!-- open: 72, close: 71 --><font class="lisp">:before</font><!-- open: 72, close: 72 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 73, close: 72 --><font class="lisp">:after</font><!-- open: 73, close: 73 --> <!-- MATCHED MATCHED MATCHED --> are allowed.
See <font color='red'>LINK:(</font>method-combination).

<!-- open: 74, close: 73 --><font class="italic">lambda-list</font><!-- open: 74, close: 74 --> <!-- MATCHED MATCHED MATCHED --> describes the arguments and "aux variables" of the
function; the first argument which is the message keyword is automatically handled
and not mentioned here.  Note that methods may not have <!-- open: 75, close: 74 --><font class="lisp">&amp;quote</font><!-- open: 75, close: 75 --> <!-- MATCHED MATCHED MATCHED --> arguments,
that is they must be functions, not special forms.
<!-- open: 76, close: 75 --><font class="italic">form1</font><!-- open: 76, close: 76 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 77, close: 76 --><font class="italic">form2</font><!-- open: 77, close: 77 --> <!-- MATCHED MATCHED MATCHED -->, etc. are the function body.

The variant form
<pre class='lisp'>
(defmethod (<!-- open: 78, close: 77 --><font class="italic">flavor-name</font><!-- open: 78, close: 78 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 79, close: 78 --><font class="italic">message</font><!-- open: 79, close: 79 --> <!-- MATCHED MATCHED MATCHED -->) <!-- open: 80, close: 79 --><font class="italic">function</font><!-- open: 80, close: 80 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
where <!-- open: 81, close: 80 --><font class="italic">function</font><!-- open: 81, close: 81 --> <!-- MATCHED MATCHED MATCHED --> is a symbol, says that <!-- open: 82, close: 81 --><font class="italic">flavor-name</font><!-- open: 82, close: 82 --> <!-- MATCHED MATCHED MATCHED -->'s method
for <!-- open: 83, close: 82 --><font class="italic">message</font><!-- open: 83, close: 83 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 84, close: 83 --><font class="italic">function</font><!-- open: 84, close: 84 --> <!-- MATCHED MATCHED MATCHED -->, a symbol which names a function.
That function must take appropriate arguments; the first argument is
the message keyword.

Note that <!-- open: 85, close: 84 --><font class="lisp">defmethod</font><!-- open: 85, close: 85 --> <!-- MATCHED MATCHED MATCHED --> is also used for defining class methods,
in the case where <!-- open: 86, close: 85 --><font class="italic">flavor-name</font><!-- open: 86, close: 86 --> <!-- MATCHED MATCHED MATCHED --> is the name of a class rather
than of a flavor.  See <font color='red'>LINK:(</font>class).
</div>

<div class='defvar' id='self'><font class='exdent'><font class='funcname' id='self'>self</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->When a message is sent to an object, the variable <!-- open: 87, close: 86 --><font class="lisp">self</font><!-- open: 87, close: 87 --> <!-- MATCHED MATCHED MATCHED --> is automatically
bound to that object, for the benefit of methods which want to manipulate
the object itself (as opposed to its instance variables).
</div>

<div class='defmac' id='declare-flavor-instance-variables'><font class='exdent'><font class='funcname' id='declare-flavor-instance-variables'>declare-flavor-instance-variables</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->Sometimes you will write a function which is not itself a method, but
which is to be called by methods and wants to be able to access the
instance variables of the object <!-- open: 88, close: 87 --><font class="lisp">self</font><!-- open: 88, close: 88 --> <!-- MATCHED MATCHED MATCHED -->.  The form
<pre class='lisp'>
(declare-flavor-instance-variables (<!-- open: 89, close: 88 --><font class="italic">flavor-name</font><!-- open: 89, close: 89 --> <!-- MATCHED MATCHED MATCHED -->)
  <!-- open: 90, close: 89 --><font class="italic">function-definition</font><!-- open: 90, close: 90 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
surrounds the <!-- open: 91, close: 90 --><font class="italic">function-definition</font><!-- open: 91, close: 91 --> <!-- MATCHED MATCHED MATCHED --> with a declaration of the
instance variables for the specified flavor, which will make them
accessible by name.  Currently this works by declaring them as special
variables, but this implementation may be changed in the future.
Note that it is only legal to call a function defined this way while executing
inside a method for an object of the specified flavor, or of some
flavor built upon it.
</div>

<div class='defun' id='recompile-flavor'>
  <font class='exdent'>
    <font class='funcname'>recompile-flavor </font>
    <font class='italic' color='purple'>flavor-name &optional single-message (use-old-combined-methods t) (do-dependents t)</font>
  </font><br>
Updates the internal data of the flavor and any flavors that depend on it.
If <!-- open: 92, close: 91 --><font class="italic">single-message</font><!-- open: 92, close: 92 --> <!-- MATCHED MATCHED MATCHED --> is supplied non-<!-- open: 93, close: 92 --><font class="lisp">nil</font><!-- open: 93, close: 93 --> <!-- MATCHED MATCHED MATCHED -->, only the methods for that
message are changed.  The system does this when you define a new method that
did not previously exist.
If <!-- open: 94, close: 93 --><font class="italic">use-old-combined-methods</font><!-- open: 94, close: 94 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 95, close: 94 --><font class="lisp">nil</font><!-- open: 95, close: 95 --> <!-- MATCHED MATCHED MATCHED -->, automatically-generated functions
to call multiple methods or to contain code generated by wrappers will be regenerated.
Normally these are only regenerated if the set of methods they are based on has changed.
If you change a wrapper, you must do <!-- open: 96, close: 95 --><font class="lisp">recompile-flavor</font><!-- open: 96, close: 96 --> <!-- MATCHED MATCHED MATCHED --> with third argument <!-- open: 97, close: 96 --><font class="lisp">nil</font><!-- open: 97, close: 97 --> <!-- MATCHED MATCHED MATCHED -->
in order to make the new wrapper take effect.
If <!-- open: 98, close: 97 --><font class="italic">do-dependents</font><!-- open: 98, close: 98 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 99, close: 98 --><font class="lisp">nil</font><!-- open: 99, close: 99 --> <!-- MATCHED MATCHED MATCHED -->, only the specific flavor you specified
will be recompiled.  Normally it and all flavors that depend on it will be recompiled.

<!-- open: 100, close: 99 --><font class="lisp">recompile-flavor</font><!-- open: 100, close: 100 --> <!-- MATCHED MATCHED MATCHED --> only affects flavors that have already been compiled.
Typically this means it affects flavors that have been instantiated,
but does not bother with mixins.
</div>

<div class='defmac' id='compile-flavor-methods'><font class='exdent'><font class='funcname' id='compile-flavor-methods'>compile-flavor-methods</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->The form <!-- open: 101, close: 100 --><font class="lisp">(compile-flavor-methods <!-- open: 102, close: 100 --><font class="italic">flavor-name-1</font><!-- open: 102, close: 101 --> <!-- open: 103, close: 101 --><font class="italic">flavor-name-2</font><!-- open: 103, close: 102 -->...)</font><!-- open: 103, close: 103 --> <!-- MATCHED MATCHED MATCHED -->,
placed in a file to be compiled, will cause the compiler to include the automatically
generated methods for the named flavors in the resulting <!-- open: 104, close: 103 --><font class="lisp">qfasl</font><!-- open: 104, close: 104 --> <!-- MATCHED MATCHED MATCHED --> file, provided
all of the necessary flavor definitions have been made.  Use of <!-- open: 105, close: 104 --><font class="lisp">compile-flavor-methods</font><!-- open: 105, close: 105 --> <!-- MATCHED MATCHED MATCHED -->
for all flavors that are going to be instantiated
is recommended to eliminate the need to call the compiler at run time (the compiler
will still be called if incompatible changes have been made, such as addition or
deletion of methods that must be called by a combined method).
</div>

<div class='defmac' id='defwrapper'><font class='exdent'><font class='funcname' id='defwrapper'>defwrapper</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->Sometimes the way the flavor system combines the methods of different
flavors (the daemon system) is not powerful enough.  In that case <!-- open: 106, close: 105 --><font class="lisp">defwrapper</font><!-- open: 106, close: 106 --> <!-- MATCHED MATCHED MATCHED -->
can be used to define a macro which expands into code which is wrapped around
the invocation of the methods.  This is best explained by an example;
suppose you needed a lock locked during the processing of the
<!-- open: 107, close: 106 --><font class="lisp">:foo</font><!-- open: 107, close: 107 --> <!-- MATCHED MATCHED MATCHED --> message, which takes the arguments <!-- open: 108, close: 107 --><font class="lisp">arg1</font><!-- open: 108, close: 108 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 109, close: 108 --><font class="lisp">arg2</font><!-- open: 109, close: 109 --> <!-- MATCHED MATCHED MATCHED -->,
and you have a <!-- open: 110, close: 109 --><font class="lisp">lock-frobboz</font><!-- open: 110, close: 110 --> <!-- MATCHED MATCHED MATCHED --> special-form which knows how to lock the lock
(presumably it generates an <!-- open: 111, close: 110 --><font class="lisp">unwind-protect</font><!-- open: 111, close: 111 --> <!-- MATCHED MATCHED MATCHED -->).
<pre class='lisp'>
(defwrapper (<!-- open: 112, close: 111 --><font class="italic">flavor</font><!-- open: 112, close: 112 --> <!-- MATCHED MATCHED MATCHED --> :foo) ((arg1 arg2) . body)
  `(lock-frobboz (self ,arg1)
     ,@body))
</pre>
The use of the <!-- open: 113, close: 112 --><font class="lisp">body</font><!-- open: 113, close: 113 --> <!-- MATCHED MATCHED MATCHED --> macro-argument prevents the <!-- open: 114, close: 113 --><font class="lisp">defwrapper</font><!-- open: 114, close: 114 --> <!-- MATCHED MATCHED MATCHED -->'ed
macro from knowing the exact implementation and allows several <!-- open: 115, close: 114 --><font class="lisp">defwrapper</font><!-- open: 115, close: 115 --> <!-- MATCHED MATCHED MATCHED -->'s
from different flavors to be combined properly.

If you change a wrapper, the change may not take effect automatically.  You must
use <!-- open: 116, close: 115 --><font class="lisp">recompile-flavor</font><!-- open: 116, close: 116 --> <!-- MATCHED MATCHED MATCHED --> with a third argument of <!-- open: 117, close: 116 --><font class="lisp">nil</font><!-- open: 117, close: 117 --> <!-- MATCHED MATCHED MATCHED --> to force the effect
to propagate into the compiled code which the system generates to implement the
flavor.  The reason for this is that the flavor system cannot reliably tell the
difference between reloading a file containing a wrapper and really redefining
the wrapper to be different, and propagating a change to a wrapper is expensive.
[This may be fixed in the future.]
</div>

<div class='defun' id='funcall-self'>
  <font class='exdent'>
    <font class='funcname'>funcall-self </font>
    <font class='italic' color='purple'>message arguments...</font>
  </font><br>
When <!-- open: 118, close: 117 --><font class="lisp">self</font><!-- open: 118, close: 118 --> <!-- MATCHED MATCHED MATCHED --> is an instance or an entity, <!-- open: 119, close: 118 --><font class="lisp">(funcall-self <!-- open: 120, close: 118 --><font class="italic">args</font><!-- open: 120, close: 119 -->...)</font><!-- open: 120, close: 120 --> <!-- MATCHED MATCHED MATCHED --> has the
same effect as <!-- open: 121, close: 120 --><font class="lisp">(funcall self <!-- open: 122, close: 120 --><font class="italic">args</font><!-- open: 122, close: 121 -->...)</font><!-- open: 122, close: 122 --> <!-- MATCHED MATCHED MATCHED --> except that it is a little
faster since it doesn't bother to think about re-binding the instance variables.
If <!-- open: 123, close: 122 --><font class="lisp">self</font><!-- open: 123, close: 123 --> <!-- MATCHED MATCHED MATCHED --> is not an instance nor an entity, <!-- open: 124, close: 123 --><font class="lisp">funcall-self</font><!-- open: 124, close: 124 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 125, close: 124 --><font class="lisp">funcall</font><!-- open: 125, close: 125 --> <!-- MATCHED MATCHED MATCHED -->
do the same thing.
</div>

<div class='defun' id='lexpr-funcall-self'>
  <font class='exdent'>
    <font class='funcname'>lexpr-funcall-self </font>
    <font class='italic' color='purple'>message arguments... list-of-arguments</font>
  </font><br>
When <!-- open: 126, close: 125 --><font class="lisp">self</font><!-- open: 126, close: 126 --> <!-- MATCHED MATCHED MATCHED --> is an instance or an entity, <!-- open: 127, close: 126 --><font class="lisp">(lexpr-funcall-self <!-- open: 128, close: 126 --><font class="italic">args</font><!-- open: 128, close: 127 -->...)</font><!-- open: 128, close: 128 --> <!-- MATCHED MATCHED MATCHED --> has the
same effect as <!-- open: 129, close: 128 --><font class="lisp">(lexpr-funcall self <!-- open: 130, close: 128 --><font class="italic">args</font><!-- open: 130, close: 129 -->...)</font><!-- open: 130, close: 130 --> <!-- MATCHED MATCHED MATCHED --> except that it is a little
faster since it doesn't bother to think about re-binding the instance variables.
If <!-- open: 131, close: 130 --><font class="lisp">self</font><!-- open: 131, close: 131 --> <!-- MATCHED MATCHED MATCHED --> is not an instance nor an entity, <!-- open: 132, close: 131 --><font class="lisp">lexpr-funcall-self</font><!-- open: 132, close: 132 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 133, close: 132 --><font class="lisp">lexpr-funcall</font><!-- open: 133, close: 133 --> <!-- MATCHED MATCHED MATCHED -->
do the same thing.
</div>

<!-- *** Should symeval-in-instance and friends be globalized and documented? -->

<div class='section' id='21.3'>21.3 </div>
There are quite a few options to <!-- open: 134, close: 133 --><font class="lisp">defflavor</font><!-- open: 134, close: 134 --> <!-- MATCHED MATCHED MATCHED -->.  They are all described here,
although some are for very specialized purposes and not of interest to most users.
<table>
<tr valign='top'><td colspan='2'><font class='lisp'> :gettable-instance-variables</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Enables automatic generation of methods for getting the values of instance
variables.  The message name is the name of the variable, in the keyword
package (i.e. put a colon in front of it.)  If this option is given with
arguments, only those instance variables get methods; if the keyword is
given by itself all the instance variables listed in this <!-- open: 135, close: 134 --><font class="lisp">defflavor</font><!-- open: 135, close: 135 --> <!-- MATCHED MATCHED MATCHED -->
get methods.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :settable-instance-variables</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Enables automatic generation of methods for setting the values of
instance variables.  The message name is "<!-- open: 136, close: 135 --><font class="lisp">:set-</font><!-- open: 136, close: 136 --> <!-- MATCHED MATCHED MATCHED -->" followed by the
name of the variable.  If this option is given with arguments, only those instance
variables get methods; if the keyword is given by itself all the
instance variables listed in this <!-- open: 137, close: 136 --><font class="lisp">defflavor</font><!-- open: 137, close: 137 --> <!-- MATCHED MATCHED MATCHED --> get methods.
All settable instance variables are also automatically made gettable
and initable.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :initable-instance-variables</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The instance variables listed as arguments, or all instance variables
listed in this <!-- open: 138, close: 137 --><font class="lisp">defflavor</font><!-- open: 138, close: 138 --> <!-- MATCHED MATCHED MATCHED --> if the keyword is given alone, are
made <!-- open: 139, close: 138 --><font class="italic">initable</font><!-- open: 139, close: 139 --> <!-- MATCHED MATCHED MATCHED -->.  This means that they can be initialized through
use of a keyword (colon the name of the variable) in the initialization property-list.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :init-keywords</font></td><td>The arguments are declared to be keywords in the initialization property-list
which are processed by this flavor's <!-- open: 140, close: 139 --><font class="lisp">:init</font><!-- open: 140, close: 140 --> <!-- MATCHED MATCHED MATCHED --> methods.  This is just used
by error-checking which looks for entries (presumably misspelled) in
the initialization property-list which are not handled by any component
flavor of the object being created, neither as initable-instance-variables
nor as init-keywords.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :default-init-plist</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The arguments are alternating keywords and values, like a
property-list.  When the flavor is instantiated, if the init-plist does
not contain one of these keywords, that keyword and corresponding value
are put in.  This allows one component flavor to default an option to
another component flavor.  The values are only evaluated if they are used.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :required-instance-variables</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Declares that any flavor incorporating this one which is instantiated
into an object will contain the instance variables given as arguments.  The difference
between listing instance variables here and listing them at the front of
the <!-- open: 141, close: 140 --><font class="lisp">defflavor</font><!-- open: 141, close: 141 --> <!-- MATCHED MATCHED MATCHED --> is that the latter declares that this flavor "owns"
those variables and will take care of initializing them, while the former
declares that this flavor depends on those variables but that some other
flavor must be provided to manage them and whatever features are implied by them.
Required instance variables may be freely accessed by methods just like
normal instance variables.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :required-methods</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The arguments are names of messages which any flavor incorporating this one
must handle.  An error occurs if there is an attempt to instantiate such
a flavor and it is lacking a method for one of these messages.
Typically this option appears in the <!-- open: 142, close: 141 --><font class="lisp">defflavor</font><!-- open: 142, close: 142 --> <!-- MATCHED MATCHED MATCHED --> for a base flavor.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :included-flavors</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The arguments are names of flavors to be included in this flavor.  The difference
between declaring flavors here and declaring them at the top of the <!-- open: 143, close: 142 --><font class="lisp">defflavor</font><!-- open: 143, close: 143 --> <!-- MATCHED MATCHED MATCHED -->
is that when component flavors are combined, all the included flavors come
after all the regular flavors.  Thus included flavors act like defaults.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :no-vanilla-flavor</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Unless this option is specified, <!-- open: 144, close: 143 --><font class="lisp">si:vanilla-flavor</font><!-- open: 144, close: 144 --> <!-- MATCHED MATCHED MATCHED --> is included (in the
sense of the <!-- open: 145, close: 144 --><font class="lisp">:included-flavors</font><!-- open: 145, close: 145 --> <!-- MATCHED MATCHED MATCHED --> option).  <!-- open: 146, close: 145 --><font class="lisp">vanilla-flavor</font><!-- open: 146, close: 146 --> <!-- MATCHED MATCHED MATCHED --> provides
some default methods for the <!-- open: 147, close: 146 --><font class="lisp">:print</font><!-- open: 147, close: 147 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 148, close: 147 --><font class="lisp">:describe</font><!-- open: 148, close: 148 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 149, close: 148 --><font class="lisp">:which-operations</font><!-- open: 149, close: 149 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 150, close: 149 --><font class="lisp">:eval-inside-yourself</font><!-- open: 150, close: 150 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 151, close: 150 --><font class="lisp">:funcall-inside-yourself</font><!-- open: 151, close: 151 --> <!-- MATCHED MATCHED MATCHED --> messages.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :default-handler</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The argument is the name of a function which is to be called when a message
is received for which there is no method.  If this option is not specified
on any component flavor, it defaults to a function which will signal an error.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :ordered-instance-variables</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The arguments are names of instance variables which must appear first (and in this order)
in all instances of this flavor, or any flavor depending on this flavor.
This is used for instance variables which are specially known about by
microcode, and in connection with the <!-- open: 152, close: 151 --><font class="lisp">:outside-accessible-instance-variables</font><!-- open: 152, close: 152 --> <!-- MATCHED MATCHED MATCHED -->
option.  If the keyword is given alone, the arguments default to the list
of instance variables given at the top of this <!-- open: 153, close: 152 --><font class="lisp">defflavor</font><!-- open: 153, close: 153 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :outside-accessible-instance-variables</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The arguments are instance variables which are to be accessible from
"outside" of this object, that is from functions other than methods.
A macro (actually a <!-- open: 154, close: 153 --><font class="lisp">defsubst</font><!-- open: 154, close: 154 --> <!-- MATCHED MATCHED MATCHED -->) is defined which takes an object of
this flavor as an argument and returns the value of the instance variable;
<!-- open: 155, close: 154 --><font class="lisp">setf</font><!-- open: 155, close: 155 --> <!-- MATCHED MATCHED MATCHED --> may be used to set the value of the instance variable.  The name
of the macro is the name of the flavor concatenated with a hyphen and the
name of the instance variable.  These macros are similar to the accessor
macros created by <!-- open: 156, close: 155 --><font class="lisp">defstruct</font><!-- open: 156, close: 156 --> <!-- MATCHED MATCHED MATCHED --> (see <a href='dfstr.html#defstruct'>this link</a>.)

If the instance variable is declared to
be ordered, the macro will know its relative position in the instance and
generate very quick code to access it; otherwise the position has
to be computed at run-time, which takes substantially longer but doesn't
build the details of the structure of the instance into compiled code.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :select-method-order</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>This is purely an efficiency hack.  The arguments are names of messages
which are frequently used or for which speed is important.  Their methods
are moved to the front of the method table so that they are accessed
more quickly.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :method-combination</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Declares the way that methods from different flavors will be combined.
Each "argument" to this option is a list <!-- open: 157, close: 156 --><font class="lisp">(<!-- open: 158, close: 156 --><font class="italic">type order message1 message2</font><!-- open: 158, close: 157 -->...)</font><!-- open: 158, close: 158 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 159, close: 158 --><font class="italic">Message1</font><!-- open: 159, close: 159 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 160, close: 159 --><font class="italic">message2</font><!-- open: 160, close: 160 --> <!-- MATCHED MATCHED MATCHED -->, etc. are names of messages whose methods
are to be combined in the declared fashion.  <!-- open: 161, close: 160 --><font class="italic">Type</font><!-- open: 161, close: 161 --> <!-- MATCHED MATCHED MATCHED --> is a keyword which
is a defined type of combination, see <font color='red'>LINK:(</font>method-combination).  <!-- open: 162, close: 161 --><font class="italic">Order</font><!-- open: 162, close: 162 --> <!-- MATCHED MATCHED MATCHED -->
is a keyword whose interpretation is up to <!-- open: 163, close: 162 --><font class="italic">type</font><!-- open: 163, close: 163 --> <!-- MATCHED MATCHED MATCHED -->; typically it is
either <!-- open: 164, close: 163 --><font class="lisp">:base-flavor-first</font><!-- open: 164, close: 164 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 165, close: 164 --><font class="lisp">:base-flavor-last</font><!-- open: 165, close: 165 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :documentation</font></td><td>The list of arguments to this option is remembered on the flavor's property
list as the <!-- open: 166, close: 165 --><font class="lisp">:documentation</font><!-- open: 166, close: 166 --> <!-- MATCHED MATCHED MATCHED --> property.  The (loose) standard for what can
be in this list is as follows; this may be extended in the future.  A string
is documentation on what the flavor is for; this may consist of a brief
overview in the first line, then several paragraphs of detailed documentation.
A symbol is one of the following keywords:
<table>
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :mixin</font></td><td>A flavor that you may want to mix with others to provide a useful feature.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :essential-mixin</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>A flavor that must be mixed in to all flavors of its class, or inappropriate
behavior will ensue.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :lowlevel-mixin</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>A mixin used only to build a mixin.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :combination</font></td><td>A combination of flavors for a specific purpose.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :special-purpose</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>A flavor used for some internal or hackish purpose, which you aren't likely
to want yourself.
</td></tr><!-- item_ --></table><!-- end table -->

</table><!-- end table -->


<div class='section' id='21.4'>21.4 </div>
<div class='defun' id='instantiate-flavor'>
  <font class='exdent'>
    <font class='funcname'>instantiate-flavor </font>
    <font class='italic' color='purple'>flavor-name init-plist &optional send-init-message-p return-unhandled-keywords area</font>
  </font><br>
This function creates and returns an instance of the specified flavor.
<!-- open: 167, close: 166 --><font class="italic">init-plist</font><!-- open: 167, close: 167 --> <!-- MATCHED MATCHED MATCHED --> is a disembodied property list, such as a locative to
a cell containing a list of alternating keywords and values,
which controls how the instance is initialized, as explained below.
This property list may get modified; beware!

First, if the flavor's method-table and other internal information have
not been computed or are not up to date, they are computed.  This may
take a substantial amount of time and invoke the compiler, but will
only happen once for a particular flavor no matter how many instances
you make, unless you change something.

Next, the instance variables are initialized, in several ways.
If an instance variable is declared initable, and a keyword with
the same spelling as its name appears in <!-- open: 168, close: 167 --><font class="italic">init-plist</font><!-- open: 168, close: 168 --> <!-- MATCHED MATCHED MATCHED -->, it is set
to the value specified after that keyword.  If an instance variable
does not get initialized this way, and an initialization form was
specified for it in a <!-- open: 169, close: 168 --><font class="lisp">defflavor</font><!-- open: 169, close: 169 --> <!-- MATCHED MATCHED MATCHED -->, that form is evaluated and the
variable is set to the result.  The initialization form may not depend
on any instance variables nor on <!-- open: 170, close: 169 --><font class="lisp">self</font><!-- open: 170, close: 170 --> <!-- MATCHED MATCHED MATCHED -->; it will not be evaluated in the "inside"
environment in which methods are called.
If an instance variable does not get initialized either of these ways
it will be left unbound; presumably an <!-- open: 171, close: 170 --><font class="lisp">:init</font><!-- open: 171, close: 171 --> <!-- MATCHED MATCHED MATCHED --> method should initialize it.

If any keyword appears in the <!-- open: 172, close: 171 --><font class="italic">init-plist</font><!-- open: 172, close: 172 --> <!-- MATCHED MATCHED MATCHED --> but is not used to initialize
an instance variable and is not declared in an <!-- open: 173, close: 172 --><font class="lisp">:init-keywords</font><!-- open: 173, close: 173 --> <!-- MATCHED MATCHED MATCHED --> option,
it is presumed to be a misspelling.  If the <!-- open: 174, close: 173 --><font class="italic">return-unhandled-keywords</font><!-- open: 174, close: 174 --> <!-- MATCHED MATCHED MATCHED -->
argument is not supplied, such keywords are complained about by signalling
an error.  But if <!-- open: 175, close: 174 --><font class="italic">return-unhandled-keywords</font><!-- open: 175, close: 175 --> <!-- MATCHED MATCHED MATCHED --> is supplied non-<!-- open: 176, close: 175 --><font class="lisp">nil</font><!-- open: 176, close: 176 --> <!-- MATCHED MATCHED MATCHED -->,
a list of such keywords is returned as the second value of <!-- open: 177, close: 176 --><font class="lisp">instantiate-flavor</font><!-- open: 177, close: 177 --> <!-- MATCHED MATCHED MATCHED -->.

If the <!-- open: 178, close: 177 --><font class="italic">send-init-message-p</font><!-- open: 178, close: 178 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied and non-<!-- open: 179, close: 178 --><font class="lisp">nil</font><!-- open: 179, close: 179 --> <!-- MATCHED MATCHED MATCHED -->, an
<!-- open: 180, close: 179 --><font class="lisp">:init</font><!-- open: 180, close: 180 --> <!-- MATCHED MATCHED MATCHED --> message is sent to the newly-created instance, with one
argument, the <!-- open: 181, close: 180 --><font class="italic">init-plist</font><!-- open: 181, close: 181 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 182, close: 181 --><font class="lisp">get</font><!-- open: 182, close: 182 --> <!-- MATCHED MATCHED MATCHED --> can be used to extract options
from this property-list.  Each flavor that needs initialization can
contribute an <!-- open: 183, close: 182 --><font class="lisp">:init</font><!-- open: 183, close: 183 --> <!-- MATCHED MATCHED MATCHED --> method.

If the <!-- open: 184, close: 183 --><font class="italic">area</font><!-- open: 184, close: 184 --> <!-- MATCHED MATCHED MATCHED --> argument is specified, it is the number of an area in which
to cons the instance; otherwise it is consed in the default area.
</div>

<div class='section' id='21.5'>21.5 </div>
Unless you specify otherwise (with the <!-- open: 185, close: 184 --><font class="lisp">:no-vanilla-flavor</font><!-- open: 185, close: 185 --> <!-- MATCHED MATCHED MATCHED --> option to
<!-- open: 186, close: 185 --><font class="lisp">defflavor</font><!-- open: 186, close: 186 --> <!-- MATCHED MATCHED MATCHED -->), every flavor <!-- open: 187, close: 186 --><font class="italic">includes</font><!-- open: 187, close: 187 --> <!-- MATCHED MATCHED MATCHED --> the "vanilla" flavor, which has no
instance variables but provides some basic useful methods.  Thus nearly every
object may be assumed to handle the following messages.

.defmessage :print stream prindepth slashify-p
The object should output its printed-representation to a stream.  The printer
sends this message when it encounters an instance or an entity.  The arguments are
the stream, the current depth in list-structure (for comparison with <!-- open: 188, close: 187 --><font class="lisp">prinlevel</font><!-- open: 188, close: 188 --> <!-- MATCHED MATCHED MATCHED -->),
and whether slashification is enabled (<!-- open: 189, close: 188 --><font class="lisp">prin1</font><!-- open: 189, close: 189 --> <!-- MATCHED MATCHED MATCHED --> vs <!-- open: 190, close: 189 --><font class="lisp">princ</font><!-- open: 190, close: 190 --> <!-- MATCHED MATCHED MATCHED -->).  Vanilla-flavor
ignores the last two arguments, and prints something
like <!-- open: 191, close: 190 --><font class="lisp">#&lt;<!-- open: 192, close: 190 --><font class="italic">flavor-name octal-address</font><!-- open: 192, close: 191 -->&gt;</font><!-- open: 192, close: 192 --> <!-- MATCHED MATCHED MATCHED -->.  The <!-- open: 193, close: 192 --><font class="italic">flavor-name</font><!-- open: 193, close: 193 --> <!-- MATCHED MATCHED MATCHED --> tells you what
type of object it is, and the <!-- open: 194, close: 193 --><font class="italic">octal-address</font><!-- open: 194, close: 194 --> <!-- MATCHED MATCHED MATCHED --> allows you to tell different objects.
.end_defmessage

.defmessage :describe
The object should describe itself.  The <!-- open: 195, close: 194 --><font class="lisp">describe</font><!-- open: 195, close: 195 --> <!-- MATCHED MATCHED MATCHED -->
function sends this message when it encounters an instance or an entity.
Vanilla-flavor outputs the object, the name of its flavor, and the names
and values of its instance-variables.
.end_defmessage

.defmessage :which-operations
The object should return a list of the messages it can handle.
Vanilla-flavor generates the list once per flavor and remembers it,
minimizing consing and compute-time.
.end_defmessage

.defmessage :eval-inside-yourself form
The argument is a form which is evaluated in an environment in which special
variables with the names of the instance variables are bound to the values
of the instance variables.  It works to <!-- open: 196, close: 195 --><font class="lisp">setq</font><!-- open: 196, close: 196 --> <!-- MATCHED MATCHED MATCHED --> one of these special variables;
the instance variable will be modified.  This is mainly intended to be used
for debugging.
.end_defmessage

.defmessage :funcall-inside-yourself function &amp;rest args
<!-- open: 197, close: 196 --><font class="italic">Function</font><!-- open: 197, close: 197 --> <!-- MATCHED MATCHED MATCHED --> is applied to <!-- open: 198, close: 197 --><font class="italic">args</font><!-- open: 198, close: 198 --> <!-- MATCHED MATCHED MATCHED --> in an environment in which special
variables with the names of the instance variables are bound to the values
of the instance variables.  It works to <!-- open: 199, close: 198 --><font class="lisp">setq</font><!-- open: 199, close: 199 --> <!-- MATCHED MATCHED MATCHED --> one of these special variables;
the instance variable will be modified.  This is mainly intended to be used
for debugging.
.end_defmessage

<div class='section' id='21.6'>21.6 </div>

The following types of method combination exist; these can be declared
with the <!-- open: 200, close: 199 --><font class="lisp">:method-combination</font><!-- open: 200, close: 200 --> <!-- MATCHED MATCHED MATCHED --> option to <!-- open: 201, close: 200 --><font class="lisp">defflavor</font><!-- open: 201, close: 201 --> <!-- MATCHED MATCHED MATCHED -->.  It is
possible to define your own types of method combination; for
information on this, see the code.  Note that for most types of method
combination other than <!-- open: 202, close: 201 --><font class="lisp">:daemon</font><!-- open: 202, close: 202 --> <!-- MATCHED MATCHED MATCHED --> you must define the order in which
the methods are combined, either <!-- open: 203, close: 202 --><font class="lisp">:base-flavor-first</font><!-- open: 203, close: 203 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 204, close: 203 --><font class="lisp">:base-flavor-last</font><!-- open: 204, close: 204 --> <!-- MATCHED MATCHED MATCHED -->.
In this context, base-flavor means the last element of the flavor's
fully-expanded list of components.

<table>
<tr valign='top'>
<td><font class='lisp'> :daemon</font></td><td>This is the default type of method combination.  All the <!-- open: 205, close: 204 --><font class="lisp">:before</font><!-- open: 205, close: 205 --> <!-- MATCHED MATCHED MATCHED -->
methods are called, then the primary (no type) method for the outermost
flavor that has one is called, then all the <!-- open: 206, close: 205 --><font class="lisp">:after</font><!-- open: 206, close: 206 --> <!-- MATCHED MATCHED MATCHED --> methods are
called.  The value returned is the value of the primary method.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :progn</font></td><td>.item1 :and
.item1 :or
All the methods are called, inside a <!-- open: 207, close: 206 --><font class="lisp">progn</font><!-- open: 207, close: 207 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 208, close: 207 --><font class="lisp">and</font><!-- open: 208, close: 208 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 209, close: 208 --><font class="lisp">or</font><!-- open: 209, close: 209 --> <!-- MATCHED MATCHED MATCHED --> special form.
No typed methods are allowed.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :list</font></td><td>Calls all the methods and returns a list of their returned values.  No typed
methods are allowed.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :inverse-list</font></td><td>Applies each method to one element of the list given as the sole
argument to the message.  No typed methods are allowed.  Returns no
particular value.  If the result of a <!-- open: 210, close: 209 --><font class="lisp">:list</font><!-- open: 210, close: 210 --> <!-- MATCHED MATCHED MATCHED -->-combined message is
sent back with an <!-- open: 211, close: 210 --><font class="lisp">:inverse-list</font><!-- open: 211, close: 211 --> <!-- MATCHED MATCHED MATCHED -->-combined message, with the same
ordering and with corresponding method definitions, each component
flavor receives the value which came from that flavor.

</td></tr><!-- item_ --></table><!-- end table -->


Which method type keywords are allowed depends on the type of method
combination selected.  Many of them allow only untyped methods.  There
are also certain methods types used for internal purposes.  Here is
a table of all the method types used in the standard system (a user
can add more, by defining new forms of method-combination).

<table>
<tr valign='top'>
<td><font class='lisp'> <!-- open: 212, close: 211 --><font class="main">(no type)</font><!-- open: 212, close: 212 --> <!-- MATCHED MATCHED MATCHED --></font></td><td>This is the most common type of method.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :before</font></td><td>.item1 :after
Used by <!-- open: 213, close: 212 --><font class="lisp">:daemon</font><!-- open: 213, close: 213 --> <!-- MATCHED MATCHED MATCHED --> method-combination.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :default</font></td><td>A <!-- open: 214, close: 213 --><font class="lisp">:default</font><!-- open: 214, close: 214 --> <!-- MATCHED MATCHED MATCHED --> method is treated as untyped if there are no other methods for
the message among any of the component flavors.  Otherwise it is ignored.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :wrapper</font></td><td>Used internally by <!-- open: 215, close: 214 --><font class="lisp">defwrapper</font><!-- open: 215, close: 215 --> <!-- MATCHED MATCHED MATCHED -->.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> :combined</font></td><td>Used internally for automatically-generated <!-- open: 216, close: 215 --><font class="italic">combined</font><!-- open: 216, close: 216 --> <!-- MATCHED MATCHED MATCHED --> methods.
</td></tr><!-- item_ --></table><!-- end table -->


<div class='section' id='21.7'>21.7 </div>
An object which is an instance of a flavor is implemented using the
data type <!-- open: 217, close: 216 --><font class="lisp">dtp-instance</font><!-- open: 217, close: 217 --> <!-- MATCHED MATCHED MATCHED -->.  The representation is a vector whose
first element, tagged with <!-- open: 218, close: 217 --><font class="lisp">dtp-instance-header</font><!-- open: 218, close: 218 --> <!-- MATCHED MATCHED MATCHED -->, points to the
internal data for the flavor, and whose remaining elements are value
cells containing the values of the instance variables.  The internal
data for the flavor, known to the microcode as an "instance descriptor",
is a <!-- open: 219, close: 218 --><font class="lisp">defstruct</font><!-- open: 219, close: 219 --> <!-- MATCHED MATCHED MATCHED --> which appears on the <!-- open: 220, close: 219 --><font class="lisp">si:flavor</font><!-- open: 220, close: 220 --> <!-- MATCHED MATCHED MATCHED --> property
of the flavor name.  It contains, among other things, the name of the
flavor, the size of an instance, the table of methods for handling
messages, and information for accessing the instance variables.

<!-- open: 221, close: 220 --><font class="lisp">defflavor</font><!-- open: 221, close: 221 --> <!-- MATCHED MATCHED MATCHED --> creates such a data structure for each flavor, and
links them together according to the dependency relationships
between flavors.

A message is sent to an instance simply by calling it as a function,
with the first argument the message keyword.
The microcode binds <!-- open: 222, close: 221 --><font class="lisp">self</font><!-- open: 222, close: 222 --> <!-- MATCHED MATCHED MATCHED --> to the object, binds the instance
variables (as <!-- open: 223, close: 222 --><font class="lisp">special</font><!-- open: 223, close: 223 --> <!-- MATCHED MATCHED MATCHED --> closure variables) to the value cell slots in
the instance, and calls a <!-- open: 224, close: 223 --><font class="lisp">dtp-select-method</font><!-- open: 224, close: 224 --> <!-- MATCHED MATCHED MATCHED --> associated with
the flavor.  This <!-- open: 225, close: 224 --><font class="lisp">dtp-select-method</font><!-- open: 225, close: 225 --> <!-- MATCHED MATCHED MATCHED --> associates the message keyword
to the actual function to be called.  If there is only one method,
this is that method, otherwise it is an automatically-generated function
which calls the appropriate methods in the right order.
If there are wrappers, they are incorporated into this automatically-generated function.

There is presently an implementation restriction that when using daemons,
the primary method may return at most three values if there are any <!-- open: 226, close: 225 --><font class="lisp">:after</font><!-- open: 226, close: 226 --> <!-- MATCHED MATCHED MATCHED -->
daemons.  This is because the combined method needs a place to remember the
values while it calls the daemons.  This will be fixed some day.

The function-specifier syntax <!-- open: 227, close: 226 --><font class="lisp">(:method <!-- open: 228, close: 226 --><font class="italic">flavor-name optional-method-type message-name</font><!-- open: 228, close: 227 -->)</font><!-- open: 228, close: 228 --> <!-- MATCHED MATCHED MATCHED -->
is understood by <!-- open: 229, close: 228 --><font class="lisp">fdefine</font><!-- open: 229, close: 229 --> <!-- MATCHED MATCHED MATCHED --> and related functions, for both flavor methods
and class methods.
</body>
</html>

